Working with ebuild

Updated 24 September 2019

Contents

emerge and ebuild

The ebuild program is a low-level interface of Portage. With it you can perform certain actions on ebuilds. For instance, you can perform some installation steps manually.

ebuild is a tool intended mainly for developers. More detailed information can be found in [the developer's handbook] (http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml). However, we will explain which ebuild instances are called by Portage at different stages of installation and how to do post-configuration actions, supported by some packages.

Manual installation

Source code and checksums

Whenever you call the ebuild command for an ebuild file, the checksums of all the relevant files is checked to see if they match the checksums of the files specified in Manifest or the files/digest-[HTML_REMOVED]-[HTML_REMOVED] file. The check is performed after downloading the sources.

To fetch source code with ebuild, run:

ebuild path/to/file-ebuild fetch

If the md5 checksum does not match the one specified in the Manifest file, or one of the uploaded files does not match the description in files/digest[HTML_REMOVED]+, you will get an error message similar to this one:

!!! File is corrupt or incomplete. (Digests do not match)
>>> our recorded digest: db20421ce35e8e54346e3ef19e60e4ee
>>>  your file's digest: f10392b7c0b2bbc463ad09642606a7d6

The next line highlights the defective file.

If you are absolutely sure that the downloaded source code and the ebuild file itself are exactly what you need, you can rebuild the Manifest and digest-[HTML_REMOVED] files with the digest function of ebuild. Here is how Manifest and digest are created:

ebuild path/to/file-ebuild digestra

Extract sources

To unpack the source code to @/var/tmp/portage@ (or any other directory specified in make_conf), use the unpack function of <<[HTML_REMOVED]>. Here is how to extract source code:

ebuild path/to/file-ebuild unpack}

This command will execute the src_unpack() function of ebuild (which by default simply unpacks a file if the src_unpack() function has not been defined). That is when all necessary patches are applied, too.

Compile from source

The next step is compilation. To compile, the src_compile() function of your ebuild will be used. Setup will be done too, if necessary. Here is how to compile:

ebuild path/to/file-ebuild compile

If you want to modify compilation instructions, we recommend that you edit the src_compile() function. But you can also trick Portage into believing that ebuild has already completed the compilation process. Run the required commands manually and create an empty .compile file in the operating directory:

touch .compiled

Move files to temporary location

At the next step, you must put collect all necessary files in a temporary directory. It will contain all files to be integrated in the operating filesystem. You can accomplish this step by running the <[HTML_REMOVED]>> installation function, which calls the src_install() function of the ebuild:

ebuild path/to/file-ebuild install

Move files to actual filesystem

The last step is to move all files to the operating file system and to register them with Portage. In ebuild, this step is called qmerge. It includes the following actions:

  • if applies, the pkg_preinst() function is called
  • all files are copied to the operating filesystem
  • and registered in Portage
  • if applies, the pkg_postinst() function is called

Run the qmerge function of ebuild to complete this step:

ebuild path/to/file-ebuild qmerge

Clean temporary files

You can remove temporary data with theclean function of ebuild:

ebuild path/to/file-ebuild clean

Go even further with ebuild

All installation commands

The merge function of ebuild allows you to extract, unpack, compile, install and locate at once:

ebuild path/to/file-ebuild merge

Configuration

Some applications provide instructions on how to further configure the installed package. Applying these instructions may require the user to be involved and, therefore, not be automatic. To initiate the configuration process, as specified in the optional config() function of the ebuild, use the 'config' command of ebuild. Here is an example of configuration:

ebuild path/to/file-ebuild config

RPM compilation

You can ask Portage to create a binary package or even an RPM from your ebuild, using the package and rpm commands respectively. These two commands are somewhat different.

  • the +package command is similar to 'merge' in many ways, performing all the necessary steps (extraction, unpacking, compilation, installation) before actually creating a package
  • the rpm command builds an RPM package from the files created after the ebuild function has completed

Examples:

creating a binary package, compatible with Portage:

ebuild path/to/file-ebuild package

creating an RPM package:

ebuild path/to/file-ebuild rpm

However, the resulting RPM will not contain any information on dependencies that are found in the ebuild file.

Getting more info

For more details about Portage, the ebuild tool and ebuild scripts, please browse the following man pages:

  • man portage - (Portage itself)
  • man emerge - (the emerge command)
  • man ebuild - (the ebuild command)
  • man 5 ebuild - (ebuild file syntax)

For additional information on development, refer to the [Developer's Handbook] (http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml).